1
2
3
4
5
6
7 package ca.uhn.cache.proxy;
8
9
10 /***
11 * An extension of <code>IMethodAdapter</code> to handle methods
12 * in which results are returned to the caller via a listener
13 * instead of as a return value. The caller is assumed to provide
14 * the listener as a method argument.
15 *
16 * If a method does not use a listener, adapt it with a
17 * <code>IMethodAdapter</code> instead.
18 *
19 * We don't handle cases where there is more than one listener argument
20 * per method.
21 *
22 * The proxy uses this interface as follows. When a caller calls a method to
23 * perform a query, it provides listener to which results are
24 * supposed to go. The proxy wraps it in a ResultListener (A) obtained from
25 * wrapListener(). Cached results are sent to this ResultListener. The proxy
26 * then calls replaceListener() to replace the caller's listener with a new
27 * listener of the same type, which sends data to a new ResultListener (B).
28 * The underlying method is called with this new argument list.
29 * ResultListener B forwards data to both the cache and ResultListener A,
30 * which in turn passes it to the caller. In summary, results follow this
31 * path as they become available: data source -> replacement
32 * listener -> ResultListener B -> cache and ResultListener A -> caller's
33 * listener.
34 *
35 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
36 * @version $Revision: 1.1 $ updated on $Date: 2005/01/24 22:53:24 $ by $Author: bryan_tripp $
37 */
38 public interface IListeningMethodAdapter extends IMethodAdapter {
39
40 /***
41 * @param theMethodArgs one of these is a listener to which the
42 * method implementation is expected to send query results.
43 * @return a wrapper around the listener to which the cache can
44 * send additional data.
45 */
46 public ResultListener wrapListener(Object[] theMethodArgs);
47
48 /***
49 * @param theMethodArgs one of these is a listener to which the
50 * method implementation is expected to send query results.
51 * @param theListener a listener to
52 * @return TODO:
53 */
54 public Object[] replaceListener(Object[] theMethodArgs, ResultListener theListener);
55
56 /***
57 * A generic listener for query results.
58 *
59 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
60 * @version $Revision: 1.1 $ updated on $Date: 2005/01/24 22:53:24 $ by $Author: bryan_tripp $
61 */
62 public static interface ResultListener {
63
64 /***
65 * @param theResult a new result
66 */
67 public void resultAvailable(Object theResult);
68 }
69
70 }